<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /fasttmp/mkdist-qt-4.3.5-1211793125/qtopia-core-opensource-src-4.3.5/src/corelib/tools/qshareddata.cpp -->
<head>
  <title>Qt 4.3: QSharedDataPointer Class Reference</title>
  <link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top" width="32"><a href="http://www.trolltech.com/products/qt"><img src="images/qt-logo.png" align="left" width="32" height="32" border="0" /></a></td>
<td width="1">&nbsp;&nbsp;</td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a>&nbsp;&middot; <a href="classes.html"><font color="#004faf">All&nbsp;Classes</font></a>&nbsp;&middot; <a href="mainclasses.html"><font color="#004faf">Main&nbsp;Classes</font></a>&nbsp;&middot; <a href="groups.html"><font color="#004faf">Grouped&nbsp;Classes</font></a>&nbsp;&middot; <a href="modules.html"><font color="#004faf">Modules</font></a>&nbsp;&middot; <a href="functions.html"><font color="#004faf">Functions</font></a></td>
<td align="right" valign="top" width="230"><a href="http://www.trolltech.com"><img src="images/trolltech-logo.png" align="right" width="203" height="32" border="0" /></a></td></tr></table><h1 align="center">QSharedDataPointer Class Reference<br /><sup><sup>[<a href="qtcore.html">QtCore</a> module]</sup></sup></h1>
<p>The QSharedDataPointer class provides a pointer to a shared data object. <a href="#details">More...</a></p>
<pre> #include &lt;QSharedDataPointer&gt;</pre><p><b>Note:</b> All the functions in this class are <a href="threads.html#reentrant">reentrant</a>.</p>
<ul>
<li><a href="qshareddatapointer-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-functions"></a>
<h3>Public Functions</h3>
<ul>
<li><div class="fn"/><b><a href="qshareddatapointer.html#QSharedDataPointer">QSharedDataPointer</a></b> ()</li>
<li><div class="fn"/><b><a href="qshareddatapointer.html#QSharedDataPointer-2">QSharedDataPointer</a></b> ( T * <i>sharedData</i> )</li>
<li><div class="fn"/><b><a href="qshareddatapointer.html#QSharedDataPointer-3">QSharedDataPointer</a></b> ( const QSharedDataPointer&lt;T&gt; &amp; <i>other</i> )</li>
<li><div class="fn"/><b><a href="qshareddatapointer.html#dtor.QSharedDataPointer">~QSharedDataPointer</a></b> ()</li>
<li><div class="fn"/>const T * <b><a href="qshareddatapointer.html#constData">constData</a></b> () const</li>
<li><div class="fn"/>T * <b><a href="qshareddatapointer.html#data">data</a></b> ()</li>
<li><div class="fn"/>const T * <b><a href="qshareddatapointer.html#data-2">data</a></b> () const</li>
<li><div class="fn"/>void <b><a href="qshareddatapointer.html#detach">detach</a></b> ()</li>
<li><div class="fn"/><b><a href="qshareddatapointer.html#operator-T--2a">operator T *</a></b> ()</li>
<li><div class="fn"/><b><a href="qshareddatapointer.html#operator-const-T--2a">operator const T *</a></b> () const</li>
<li><div class="fn"/>bool <b><a href="qshareddatapointer.html#operator-not">operator!</a></b> () const</li>
<li><div class="fn"/>bool <b><a href="qshareddatapointer.html#operator-not-eq">operator!=</a></b> ( const QSharedDataPointer&lt;T&gt; &amp; <i>other</i> ) const</li>
<li><div class="fn"/>T &amp; <b><a href="qshareddatapointer.html#operator-2a">operator*</a></b> ()</li>
<li><div class="fn"/>const T &amp; <b><a href="qshareddatapointer.html#operator-2a-2">operator*</a></b> () const</li>
<li><div class="fn"/>T * <b><a href="qshareddatapointer.html#operator--gt">operator-&gt;</a></b> ()</li>
<li><div class="fn"/>const T * <b><a href="qshareddatapointer.html#operator--gt-2">operator-&gt;</a></b> () const</li>
<li><div class="fn"/>QSharedDataPointer&lt;T&gt; &amp; <b><a href="qshareddatapointer.html#operator-eq">operator=</a></b> ( const QSharedDataPointer&lt;T&gt; &amp; <i>other</i> )</li>
<li><div class="fn"/>QSharedDataPointer &amp; <b><a href="qshareddatapointer.html#operator-eq-2">operator=</a></b> ( T * <i>sharedData</i> )</li>
<li><div class="fn"/>bool <b><a href="qshareddatapointer.html#operator-eq-eq">operator==</a></b> ( const QSharedDataPointer&lt;T&gt; &amp; <i>other</i> ) const</li>
</ul>
<a name="details"></a>
<hr />
<h2>Detailed Description</h2>
<p>The QSharedDataPointer class provides a pointer to a shared data object.</p>
<p>QSharedDataPointer&lt;T&gt; makes it easier to write your own implicitly shared classes. It handles reference counting behind the scenes in a thread-safe manner, ensuring that classes that use it can be <a href="threads.html#reentrant">reentrant</a>.</p>
<p>Implicit sharing is used throughout Qt to combine the memory and speed efficiency of pointers with the ease of use of value types. See the <a href="shared.html#shared-classes">Shared Classes</a> page for more information.</p>
<p>Let's suppose that you want to make an <tt>Employee</tt> class implicitly shared. The procedure is:</p>
<ul>
<li>Define the <tt>Employee</tt> class with a single data member variable of type QSharedDataPointer&lt;<tt>EmployeeData</tt>&gt;.</li>
<li>Define an <tt>EmployeeData</tt> class that derives from <a href="qshareddata.html">QSharedData</a> and that contains all the variables that you would normally put in <tt>Employee</tt>.</li>
</ul>
<p>To show how this works in practice, we will review the entire source code for an implicitly shared <tt>Employee</tt> class. Here's the header file that defines the <tt>Employee</tt> class:</p>
<pre> #ifndef EMPLOYEE_H
 #define EMPLOYEE_H

 #include &lt;QSharedData&gt;
 #include &lt;QString&gt;

 class EmployeeData : public QSharedData
 {
 public:
     EmployeeData();
     EmployeeData(const EmployeeData &amp;other);
     ~EmployeeData();

     int id;
     QString *name;
 };

 class Employee
 {
 public:
     Employee();
     Employee(int id, const QString &amp;name);

     void setId(int id) { d-&gt;id = id; }
     void setName(const QString &amp;name);

     int id() const { return d-&gt;id; }
     QString name() const;

 private:
     QSharedDataPointer&lt;EmployeeData&gt; d;
 };

 #endif</pre>
<p>All accesses to the data in the setter and getter functions are made through the QSharedDataPointer object <tt>d</tt>. For non-const functions, operator-&gt;() automatically calls <a href="qshareddatapointer.html#detach">detach</a>(), ensuring that modifications to one <tt>Employee</tt> object don't affect other <tt>Employee</tt> objects.</p>
<p>The <tt>EmployeeData</tt> type is a simple class that inherits <a href="qshareddata.html">QSharedData</a> and that provides a default constructor, a copy constructor, and a destructor. Normally, this is all you need in the &quot;data&quot; class.</p>
<p>Here's the implementation of the <tt>EmployeeData</tt> members:</p>
<pre> EmployeeData::EmployeeData()
 {
     id = -1;
     name = 0;
 }

 EmployeeData::EmployeeData(const EmployeeData &amp;other)
     : QSharedData(other)
 {
     id = other.id;
     if (other.name) {
         name = new QString(*other.name);
     } else {
         name = 0;
     }
 }

 EmployeeData::~EmployeeData()
 {
     delete name;
 }</pre>
<p>Let's now see how to implement the <tt>Employee</tt> constructors:</p>
<pre> Employee::Employee()
 {
     d = new EmployeeData;
 }</pre>
<p>In the default constructor, we create an object of type <tt>EmployeeData</tt> and assign it to the <tt>d</tt> pointer using operator=().</p>
<p>Behind the scenes, QSharedDataPointer automatically increments or decrements the reference count of the shared data object pointed to by <tt>d</tt>, and deletes shared objects when the reference count reaches 0.</p>
<pre> Employee::Employee(int id, const QString &amp;name)
 {
     d = new EmployeeData;
     setId(id);
     setName(name);
 }</pre>
<p>In the constructor that takes an ID and an employee's name, we also create an object of type <tt>EmployeeData</tt> and assign it to the <tt>d</tt> pointer.</p>
<pre> void Employee::setName(const QString &amp;name)
 {
     if (!d-&gt;name)
         d-&gt;name = new QString;
     *d-&gt;name = name;
 }</pre>
<p>When we use the <tt>d</tt> pointer from a non-const function, <a href="qshareddatapointer.html#detach">detach</a>() is automatically called to ensure that we work on our own copy of the data.</p>
<pre> QString Employee::name() const
 {
     if (!d-&gt;name)
         return QString();
     return *d-&gt;name;
 }</pre>
<p>When we use the <tt>d</tt> pointer in a const function, <a href="qshareddatapointer.html#detach">detach</a>() is <i>not</i> called.</p>
<p>Notice that there is no need to implement a copy constructor or assignment operator in the <tt>Employee</tt> class. This is because the C++ compiler provides default implementations that simply perform member-by-member copy. Here, the only member is <tt>d</tt>, and its operator=() simply increments a reference count (which is precisely what we want).</p>
<p>See also <a href="qshareddata.html">QSharedData</a>.</p>
<hr />
<h2>Member Function Documentation</h2>
<h3 class="fn"><a name="QSharedDataPointer"></a>QSharedDataPointer::QSharedDataPointer ()</h3>
<p>Constructs a <a href="qshareddatapointer.html">QSharedDataPointer</a> initialized with a null pointer.</p>
<h3 class="fn"><a name="QSharedDataPointer-2"></a>QSharedDataPointer::QSharedDataPointer ( T * <i>sharedData</i> )</h3>
<p>Constructs a <a href="qshareddatapointer.html">QSharedDataPointer</a> that points to <i>sharedData</i>.</p>
<p>This function automatically increments <i>sharedData</i>'s reference count.</p>
<h3 class="fn"><a name="QSharedDataPointer-3"></a>QSharedDataPointer::QSharedDataPointer ( const QSharedDataPointer&lt;T&gt; &amp; <i>other</i> )</h3>
<p>Constructs a copy of <i>other</i>.</p>
<p>This function automatically increments the reference count of the shared data object pointed to by <i>other</i>.</p>
<h3 class="fn"><a name="dtor.QSharedDataPointer"></a>QSharedDataPointer::~QSharedDataPointer ()</h3>
<p>Destroys the <a href="qshareddatapointer.html">QSharedDataPointer</a>.</p>
<p>This function automatically decrements the reference count of the shared object and deletes the object if the reference count reaches 0.</p>
<h3 class="fn"><a name="constData"></a>const T * QSharedDataPointer::constData () const</h3>
<p>Returns a const pointer to the shared object.</p>
<p>This function does not call <a href="qshareddatapointer.html#detach">detach</a>().</p>
<p>See also <a href="qshareddatapointer.html#data">data</a>().</p>
<h3 class="fn"><a name="data"></a>T * QSharedDataPointer::data ()</h3>
<p>Returns a pointer to the shared object.</p>
<p>This function does a <a href="qshareddatapointer.html#detach">detach</a>().</p>
<p>See also <a href="qshareddatapointer.html#constData">constData</a>().</p>
<h3 class="fn"><a name="data-2"></a>const T * QSharedDataPointer::data () const</h3>
<p>This is an overloaded member function, provided for convenience.</p>
<p>This function does not call <a href="qshareddatapointer.html#detach">detach</a>().</p>
<h3 class="fn"><a name="detach"></a>void QSharedDataPointer::detach ()</h3>
<p>If the shared data's reference count is greater than 1, creates a deep copy of the shared data.</p>
<p>This function is automatically called by <a href="qshareddatapointer.html">QSharedDataPointer</a> when necessary. You should never need to call it yourself.</p>
<h3 class="fn"><a name="operator-T--2a"></a>QSharedDataPointer::operator T * ()</h3>
<p>Returns a pointer to the shared object.</p>
<p>This function does a <a href="qshareddatapointer.html#detach">detach</a>().</p>
<p>See also <a href="qshareddatapointer.html#data">data</a>() and <a href="qshareddatapointer.html#constData">constData</a>().</p>
<h3 class="fn"><a name="operator-const-T--2a"></a>QSharedDataPointer::operator const T * () const</h3>
<p>Returns a pointer to the shared object.</p>
<p>This function does not call <a href="qshareddatapointer.html#detach">detach</a>().</p>
<h3 class="fn"><a name="operator-not"></a>bool QSharedDataPointer::operator! () const</h3>
<p>Returns true if this pointer is null; otherwise returns false.</p>
<h3 class="fn"><a name="operator-not-eq"></a>bool QSharedDataPointer::operator!= ( const QSharedDataPointer&lt;T&gt; &amp; <i>other</i> ) const</h3>
<p>Returns a true if the pointer to the shared object in <i>other</i> is not equal to to the pointer to the shared data in this else returns false.</p>
<p>This function does not call <a href="qshareddatapointer.html#detach">detach</a>().</p>
<h3 class="fn"><a name="operator-2a"></a>T &amp; QSharedDataPointer::operator* ()</h3>
<p>Provides access to the shared object's members.</p>
<p>This function does a <a href="qshareddatapointer.html#detach">detach</a>().</p>
<h3 class="fn"><a name="operator-2a-2"></a>const T &amp; QSharedDataPointer::operator* () const</h3>
<p>This is an overloaded member function, provided for convenience.</p>
<p>This function does not call <a href="qshareddatapointer.html#detach">detach</a>().</p>
<h3 class="fn"><a name="operator--gt"></a>T * QSharedDataPointer::operator-&gt; ()</h3>
<p>Provides access to the shared object's members.</p>
<p>This function does a <a href="qshareddatapointer.html#detach">detach</a>().</p>
<h3 class="fn"><a name="operator--gt-2"></a>const T * QSharedDataPointer::operator-&gt; () const</h3>
<p>This is an overloaded member function, provided for convenience.</p>
<p>This function does not call <a href="qshareddatapointer.html#detach">detach</a>().</p>
<h3 class="fn"><a name="operator-eq"></a>QSharedDataPointer&lt;T&gt; &amp; QSharedDataPointer::operator= ( const QSharedDataPointer&lt;T&gt; &amp; <i>other</i> )</h3>
<p>Assigns <i>other</i> to this pointer.</p>
<p>This function automatically increments the reference count of the shared data object pointed to by <i>other</i>, and decrements the reference count of the object previously pointed to by this <a href="qshareddatapointer.html">QSharedDataPointer</a>. If the reference count reaches 0, the shared data object is deleted.</p>
<h3 class="fn"><a name="operator-eq-2"></a>QSharedDataPointer &amp; QSharedDataPointer::operator= ( T * <i>sharedData</i> )</h3>
<p>This is an overloaded member function, provided for convenience.</p>
<p>Sets this <a href="qshareddatapointer.html">QSharedDataPointer</a> to point to <i>sharedData</i>.</p>
<p>This function automatically increments <i>sharedData</i>'s reference count, and decrements the reference count of the object previously pointed to by this <a href="qshareddatapointer.html">QSharedDataPointer</a>. If the reference count reaches 0, the shared data object is deleted.</p>
<h3 class="fn"><a name="operator-eq-eq"></a>bool QSharedDataPointer::operator== ( const QSharedDataPointer&lt;T&gt; &amp; <i>other</i> ) const</h3>
<p>Returns a true if the pointer to the shared object in <i>other</i> is equal to to the pointer to the shared data in this else returns false.</p>
<p>This function does not call <a href="qshareddatapointer.html#detach">detach</a>().</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright &copy; 2008 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt 4.3.5</div></td>
</tr></table></div></address></body>
</html>
